Readme.txt - Harness.cfm 1.04 by jeff.peters@bigfoot.com
10 Feb 2001
====================================================================
Harness is a tool that constructs test harnesses for ColdFusion applications developed using the Fusebox methodology.  It operates on the assumption that files incorporate documentation headers using the Fusedoc standard developed by Hal Helms.  
For information on Fusebox, visit http://www.fusebox.org
For information on Fusedoc, visit http://www.halhelms.com

When in the production environment, fusebox files perform their work and return control to the fusebox file.  Test harnesses are a way to provide the variables expected by a fuse and observe the output of the fuse as a unit.  This allows you to unit test your code before placing it into a full test environment, making final debugging much less painful.

In order to facilitate unit testing, we make use of a variable called "self" to tell the fuse the location to call next.  In production, of course, this variable contains the value "index.cfm", the fusebox file.  Test harnesses assign a different value to the variable, allowing the use of another process to dump variables, or whatever you wish to use in monitoring output from the fuse being unit tested.

=================
Using Harness
=================
What does Harness do?  It recurses the directory tree, starting in the specified directory, and creates a test harness for any file with a Fusebox prefix of "dsp" or "act".  If the file has a Fusedoc header in it, Harness will read the Fusedoc and do its best to create the required variables in the file's test harness.  If the file doesn't have a properly constructed Fusedoc header, Harness will still write a test harness, but the harness will only include the global initialization lines specified in harness.ini and an include statement for the file to be tested.

Before you run Harness, take a look at the harness.ini file.  This configuration file tells Harness how you'd like the global initialization lines in your test harnesses to look.  You may modify the lines as you wish; the LineCount key tells Harness how many lines to use.  For example, if you design keys for Line1 through Line17, but you set LineCount equal to 5, Harness will only use lines 1 through 5.

Once you have a harness.ini that meets with your approval, you're ready to run Harness.  It's called as a custom tag; you can place Harness.cfm and harness.ini in your Custom Tags directory or in the directory at the top of the application for which you're building harnesses.

harCall.cfm shows a sample use of Harness.  The attributes available are:

 rootDir: directory from which to start process.  
          Defaults to current directory.
          
 verbose: whether to display process information.  
          Defaults to Yes.
          
prefixes: a list of file prefixes to process.  
          Defaults to "dsp,act"
          You may use "*" to cause Harness to ignore file prefixes and create a test harness 
          for all files found.  Be careful if you use the * value--be sure you really want 
          Harness to process ALL the files in the directory structure.
          
     ini: file containing global harness settings.  
          Defaults to "harness.ini" in the directory where Harness.cfm is 
          located.

Once you've run Harness, you'll have a test harness for each file that passes the prefixes filter.  Test harnesses add a prefix of "tst_" to the file name.  Take note that you may wish to tweak your harnesses, particularly if you make use of structures in your code.  Harness 1.0 does not include auto-generation of test structures, so you'll have to add them to any harnesses that need them.  You'll also have to provide any query sims by hand.  Fortunately, if you use verbose mode, Harness will politely tell you which of your harness files use structures or queries and require your attention.  A future version of Harness is planned to auto-generate test structures, so don't be too disappointed.

Happy Testing!
- Jeff Peters

=================
Version History
=================
03 Jan 01 - 1.00 - private test release
06 Jan 01 - 1.01 - Added scope handling and optional variable 
                   handling; bug fixes
07 Jan 01 - 1.02 - Added ability to process fuse stubs as well
                   as just fusedocs.
08 Jan 01 - 1.03 - Added ability to process all files using * 
                   value in prefixes parameter.
10 Feb 01 - 1.04 - Added ==> as valid input indicator.  --> and
                   ==> are now recognized.
                   
